home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_apache2.idb / usr / freeware / apache2 / include / apr_file_io.h.z / apr_file_io.h
C/C++ Source or Header  |  2002-07-08  |  29KB  |  708 lines
  1. /* ====================================================================
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 2000-2002 The Apache Software Foundation.  All rights
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer.
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution,
  20.  *    if any, must include the following acknowledgment:
  21.  *       "This product includes software developed by the
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowledgment may appear in the software itself,
  24.  *    if and wherever such third-party acknowledgments normally appear.
  25.  *
  26.  * 4. The names "Apache" and "Apache Software Foundation" must
  27.  *    not be used to endorse or promote products derived from this
  28.  *    software without prior written permission. For written
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache",
  32.  *    nor may "Apache" appear in their name, without prior written
  33.  *    permission of the Apache Software Foundation.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  */
  54.  
  55. #ifndef APR_FILE_IO_H
  56. #define APR_FILE_IO_H
  57. /**
  58.  * @file apr_file_io.h
  59.  * @brief APR File I/O Handling
  60.  */
  61. /**
  62.  * @defgroup APR_File_IO_Handle I/O Handling Functions
  63.  * @ingroup APR_File_Handle
  64.  * @{
  65.  */
  66.  
  67.  
  68.  
  69. #include "apr.h"
  70. #include "apr_pools.h"
  71. #include "apr_time.h"
  72. #include "apr_errno.h"
  73. #include "apr_file_info.h"
  74. #include "apr_inherit.h"
  75.  
  76. #define APR_WANT_STDIO          /* for SEEK_* */
  77. #define APR_WANT_IOVEC
  78. #include "apr_want.h"
  79.  
  80. #ifdef __cplusplus
  81. extern "C" {
  82. #endif /* __cplusplus */
  83.  
  84. /**
  85.  * @defgroup apr_file_open File Open Flags/Routines
  86.  * @{
  87.  */
  88.  
  89. #define APR_READ       1           /**< Open the file for reading */
  90. #define APR_WRITE      2           /**< Open the file for writing */
  91. #define APR_CREATE     4           /**< Create the file if not there */
  92. #define APR_APPEND     8           /**< Append to the end of the file */
  93. #define APR_TRUNCATE   16          /**< Open the file and truncate to 0 length */
  94. #define APR_BINARY     32          /**< Open the file in binary mode */
  95. #define APR_EXCL       64          /**< Open should fail if APR_CREATE and file
  96.                                         exists. */
  97. #define APR_BUFFERED   128         /**< Open the file for buffered I/O */
  98. #define APR_DELONCLOSE 256         /**< Delete the file after close */
  99. #define APR_XTHREAD    512         /**< Platform dependent tag to open the file
  100.                                         for use across multiple threads */
  101. #define APR_SHARELOCK  1024        /**< Platform dependent support for higher
  102.                                         level locked read/write access to support
  103.                                         writes across process/machines */
  104. #define APR_FILE_NOCLEANUP  2048   /**< Do not register a cleanup when the file
  105.                                         is opened */
  106.  
  107. /** @} */
  108.  
  109. /**
  110.  * @defgroup APR_file_seek_flags File Seek Flags
  111.  * @{
  112.  */
  113.  
  114. /* flags for apr_file_seek */
  115. #define APR_SET SEEK_SET
  116. #define APR_CUR SEEK_CUR
  117. #define APR_END SEEK_END
  118. /** @} */
  119.  
  120. /**
  121.  * @defgroup APR_file_attrs_set File Attribute Flags
  122.  * @{
  123.  */
  124.  
  125. /* flags for apr_file_attrs_set */
  126. #define APR_FILE_ATTR_READONLY   0x01          /**< File is read-only */
  127. #define APR_FILE_ATTR_EXECUTABLE 0x02          /**< File is executable */
  128. /** @} */
  129.  
  130. /** File attributes */
  131. typedef apr_uint32_t apr_fileattrs_t;
  132.  
  133. /** should be same as whence type in lseek, POSIX defines this as int */
  134. typedef int       apr_seek_where_t;
  135.  
  136. /**
  137.  * Structure for referencing files.
  138.  * @defvar apr_file_t
  139.  */
  140. typedef struct apr_file_t         apr_file_t;
  141.  
  142. /* File lock types/flags */
  143. /**
  144.  * @defgroup APR_file_lock_types File Lock Types
  145.  * @{
  146.  */
  147.  
  148. #define APR_FLOCK_SHARED        1       /**< Shared lock. More than one process
  149.                                            or thread can hold a shared lock
  150.                                            at any given time. Essentially,
  151.                                            this is a "read lock", preventing
  152.                                            writers from establishing an
  153.                                            exclusive lock. */
  154. #define APR_FLOCK_EXCLUSIVE     2       /**< Exclusive lock. Only one process
  155.                                            may hold an exclusive lock at any
  156.                                            given time. This is analogous to
  157.                                            a "write lock". */
  158.  
  159. #define APR_FLOCK_TYPEMASK      0x000F  /**< mask to extract lock type */
  160. #define APR_FLOCK_NONBLOCK      0x0010  /**< do not block while acquiring the
  161.                                            file lock */
  162. /** @} */
  163. /**
  164.  * Open the specified file.
  165.  * @param new_file The opened file descriptor.
  166.  * @param fname The full path to the file (using / on all systems)
  167.  * @param flag Or'ed value of:
  168.  * <PRE>
  169.  *           APR_READ             open for reading
  170.  *           APR_WRITE            open for writing
  171.  *           APR_CREATE           create the file if not there
  172.  *           APR_APPEND           file ptr is set to end prior to all writes
  173.  *           APR_TRUNCATE         set length to zero if file exists
  174.  *           APR_BINARY           not a text file (This flag is ignored on 
  175.  *                                UNIX because it has no meaning)
  176.  *           APR_BUFFERED         buffer the data.  Default is non-buffered
  177.  *           APR_EXCL             return error if APR_CREATE and file exists
  178.  *           APR_DELONCLOSE       delete the file after closing.
  179.  *           APR_XTHREAD          Platform dependent tag to open the file
  180.  *                                for use across multiple threads
  181.  *           APR_SHARELOCK        Platform dependent support for higher
  182.  *                                level locked read/write access to support
  183.  *                                writes across process/machines
  184.  *           APR_FILE_NOCLEANUP   Do not register a cleanup with the pool 
  185.  *                                passed in on the <EM>cont</EM> argument (see below).
  186.  *                                The apr_os_file_t handle in apr_file_t will not
  187.  &                                be closed when the pool is destroyed.
  188.  * </PRE>
  189.  * @param perm Access permissions for file.
  190.  * @param cont The pool to use.
  191.  * @ingroup apr_file_open
  192.  * @remark If perm is APR_OS_DEFAULT and the file is being created, appropriate 
  193.  *      default permissions will be used.  *arg1 must point to a valid file_t, 
  194.  *      or NULL (in which case it will be allocated)
  195.  */
  196. APR_DECLARE(apr_status_t) apr_file_open(apr_file_t **new_file, const char *fname,
  197.                                    apr_int32_t flag, apr_fileperms_t perm,
  198.                                    apr_pool_t *cont);
  199.  
  200. /**
  201.  * Close the specified file.
  202.  * @param file The file descriptor to close.
  203.  */
  204. APR_DECLARE(apr_status_t) apr_file_close(apr_file_t *file);
  205.  
  206. /**
  207.  * delete the specified file.
  208.  * @param path The full path to the file (using / on all systems)
  209.  * @param cont The pool to use.
  210.  * @remark If the file is open, it won't be removed until all instances are closed.
  211.  */
  212. APR_DECLARE(apr_status_t) apr_file_remove(const char *path, apr_pool_t *cont);
  213.  
  214. /**
  215.  * rename the specified file.
  216.  * @param from_path The full path to the original file (using / on all systems)
  217.  * @param to_path The full path to the new file (using / on all systems)
  218.  * @param pool The pool to use.
  219.  * @warning If a file exists at the new location, then it will be overwritten.  
  220.  *      Moving files or directories across devices may not be possible.
  221.  */
  222. APR_DECLARE(apr_status_t) apr_file_rename(const char *from_path, 
  223.                                           const char *to_path,
  224.                                           apr_pool_t *pool);
  225.  
  226. /**
  227.  * copy the specified file to another file.
  228.  * @param from_path The full path to the original file (using / on all systems)
  229.  * @param to_path The full path to the new file (using / on all systems)
  230.  * @param perms Access permissions for the new file if it is created.
  231.  *     In place of the usual or'd combination of file permissions, the
  232.  *     value APR_FILE_SOURCE_PERMS may be given, in which case the source
  233.  *     file's permissions are copied.
  234.  * @param pool The pool to use.
  235.  * @remark The new file does not need to exist, it will be created if required.
  236.  * @warning If the new file already exists, its contents will be overwritten.
  237.  */
  238. APR_DECLARE(apr_status_t) apr_file_copy(const char *from_path, 
  239.                                         const char *to_path,
  240.                                         apr_fileperms_t perms,
  241.                                         apr_pool_t *pool);
  242.  
  243. /**
  244.  * append the specified file to another file.
  245.  * @param from_path The full path to the source file (using / on all systems)
  246.  * @param to_path The full path to the destination file (using / on all systems)
  247.  * @param perms Access permissions for the destination file if it is created.
  248.  *     In place of the usual or'd combination of file permissions, the
  249.  *     value APR_FILE_SOURCE_PERMS may be given, in which case the source
  250.  *     file's permissions are copied.
  251.  * @param pool The pool to use.
  252.  * @remark The new file does not need to exist, it will be created if required.
  253.  */
  254. APR_DECLARE(apr_status_t) apr_file_append(const char *from_path, 
  255.                                           const char *to_path,
  256.                                           apr_fileperms_t perms,
  257.                                           apr_pool_t *pool);
  258.  
  259. /**
  260.  * Are we at the end of the file
  261.  * @param fptr The apr file we are testing.
  262.  * @remark Returns APR_EOF if we are at the end of file, APR_SUCCESS otherwise.
  263.  */
  264. APR_DECLARE(apr_status_t) apr_file_eof(apr_file_t *fptr);
  265.  
  266. /**
  267.  * open standard error as an apr file pointer.
  268.  * @param thefile The apr file to use as stderr.
  269.  * @param cont The pool to allocate the file out of.
  270.  * @ingroup apr_file_open
  271.  */
  272. APR_DECLARE(apr_status_t) apr_file_open_stderr(apr_file_t **thefile,
  273.                                           apr_pool_t *cont);
  274.  
  275. /**
  276.  * open standard output as an apr file pointer.
  277.  * @param thefile The apr file to use as stdout.
  278.  * @param cont The pool to allocate the file out of.
  279.  * @ingroup apr_file_open
  280.  */
  281. APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile,
  282.                                           apr_pool_t *cont);
  283.  
  284. /**
  285.  * open standard input as an apr file pointer.
  286.  * @param thefile The apr file to use as stdin.
  287.  * @param cont The pool to allocate the file out of.
  288.  * @ingroup apr_file_open
  289.  */
  290. APR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile,
  291.                                               apr_pool_t *cont);
  292.  
  293. /**
  294.  * Read data from the specified file.
  295.  * @param thefile The file descriptor to read from.
  296.  * @param buf The buffer to store the data to.
  297.  * @param nbytes On entry, the number of bytes to read; on exit, the number of bytes read.
  298.  * @remark apr_file_read will read up to the specified number of bytes, but 
  299.  *         never more.  If there isn't enough data to fill that number of 
  300.  *         bytes, all of the available data is read.  The third argument is 
  301.  *         modified to reflect the number of bytes read.  If a char was put 
  302.  *         back into the stream via ungetc, it will be the first character 
  303.  *         returned. 
  304.  *
  305.  *         It is not possible for both bytes to be read and an APR_EOF or other 
  306.  *         error to be returned.
  307.  *
  308.  *         APR_EINTR is never returned.
  309.  */
  310. APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf,
  311.                                    apr_size_t *nbytes);
  312.  
  313. /**
  314.  * Write data to the specified file.
  315.  * @param thefile The file descriptor to write to.
  316.  * @param buf The buffer which contains the data.
  317.  * @param nbytes On entry, the number of bytes to write; on exit, the number 
  318.  *               of bytes written.
  319.  * @remark apr_file_write will write up to the specified number of bytes, but never 
  320.  *      more.  If the OS cannot write that many bytes, it will write as many 
  321.  *      as it can.  The third argument is modified to reflect the * number 
  322.  *      of bytes written. 
  323.  *
  324.  *      It is possible for both bytes to be written and an error to be returned.
  325.  *
  326.  *      APR_EINTR is never returned.
  327.  */
  328. APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf,
  329.                                     apr_size_t *nbytes);
  330.  
  331. /**
  332.  * Write data from iovec array to the specified file.
  333.  * @param thefile The file descriptor to write to.
  334.  * @param vec The array from which to get the data to write to the file.
  335.  * @param nvec The number of elements in the struct iovec array. This must 
  336.  *             be smaller than APR_MAX_IOVEC_SIZE.  If it isn't, the function 
  337.  *             will fail with APR_EINVAL.
  338.  * @param nbytes The number of bytes written.
  339.  * @remark It is possible for both bytes to be written and an error to be returned.
  340.  *      APR_EINTR is never returned.
  341.  *
  342.  *      apr_file_writev is available even if the underlying operating system 
  343.  *
  344.  *      doesn't provide writev().
  345.  */
  346. APR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile,
  347.                                      const struct iovec *vec,
  348.                                      apr_size_t nvec, apr_size_t *nbytes);
  349.  
  350. /**
  351.  * Read data from the specified file, ensuring that the buffer is filled
  352.  * before returning.
  353.  * @param thefile The file descriptor to read from.
  354.  * @param buf The buffer to store the data to.
  355.  * @param nbytes The number of bytes to read.
  356.  * @param bytes_read If non-NULL, this will contain the number of bytes read.
  357.  * @remark apr_file_read will read up to the specified number of bytes, but never 
  358.  *      more.  If there isn't enough data to fill that number of bytes, 
  359.  *      then the process/thread will block until it is available or EOF 
  360.  *      is reached.  If a char was put back into the stream via ungetc, 
  361.  *      it will be the first character returned. 
  362.  *
  363.  *      It is possible for both bytes to be read and an error to be 
  364.  *      returned.  And if *bytes_read is less than nbytes, an
  365.  *      accompanying error is _always_ returned.
  366.  *
  367.  *      APR_EINTR is never returned.
  368.  */
  369. APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf,
  370.                                         apr_size_t nbytes,
  371.                                         apr_size_t *bytes_read);
  372.  
  373. /**
  374.  * Write data to the specified file, ensuring that all of the data is
  375.  * written before returning.
  376.  * @param thefile The file descriptor to write to.
  377.  * @param buf The buffer which contains the data.
  378.  * @param nbytes The number of bytes to write.
  379.  * @param bytes_written If non-NULL, this will contain the number of bytes written.
  380.  * @remark apr_file_write will write up to the specified number of bytes, but never 
  381.  *      more.  If the OS cannot write that many bytes, the process/thread 
  382.  *      will block until they can be written. Exceptional error such as 
  383.  *      "out of space" or "pipe closed" will terminate with an error.
  384.  *
  385.  *      It is possible for both bytes to be written and an error to be 
  386.  *      returned.  And if *bytes_written is less than nbytes, an
  387.  *      accompanying error is _always_ returned.
  388.  *
  389.  *      APR_EINTR is never returned.
  390.  */
  391. APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile, const void *buf,
  392.                                          apr_size_t nbytes, 
  393.                                          apr_size_t *bytes_written);
  394.  
  395. /**
  396.  * put a character into the specified file.
  397.  * @param ch The character to write.
  398.  * @param thefile The file descriptor to write to
  399.  */
  400. APR_DECLARE(apr_status_t) apr_file_putc(char ch, apr_file_t *thefile);
  401.  
  402. /**
  403.  * get a character from the specified file.
  404.  * @param ch The character to write.
  405.  * @param thefile The file descriptor to write to
  406.  */
  407. APR_DECLARE(apr_status_t) apr_file_getc(char *ch, apr_file_t *thefile);
  408.  
  409. /**
  410.  * put a character back onto a specified stream.
  411.  * @param ch The character to write.
  412.  * @param thefile The file descriptor to write to
  413.  */
  414. APR_DECLARE(apr_status_t) apr_file_ungetc(char ch, apr_file_t *thefile);
  415.  
  416. /**
  417.  * Get a string from a specified file.
  418.  * @param str The buffer to store the string in. 
  419.  * @param len The length of the string
  420.  * @param thefile The file descriptor to read from
  421.  */
  422. APR_DECLARE(apr_status_t) apr_file_gets(char *str, int len, apr_file_t *thefile);
  423.  
  424. /**
  425.  * Put the string into a specified file.
  426.  * @param str The string to write. 
  427.  * @param thefile The file descriptor to write to
  428.  */
  429. APR_DECLARE(apr_status_t) apr_file_puts(const char *str, apr_file_t *thefile);
  430.  
  431. /**
  432.  * Flush the file's buffer.
  433.  * @param thefile The file descriptor to flush
  434.  */
  435. APR_DECLARE(apr_status_t) apr_file_flush(apr_file_t *thefile);
  436.  
  437. /**
  438.  * duplicate the specified file descriptor.
  439.  * @param new_file The structure to duplicate into. 
  440.  * @param old_file The file to duplicate.
  441.  * @param p The pool to use for the new file.
  442.  * @remark *arg1 must point to a valid apr_file_t, or point to NULL
  443.  */         
  444. APR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file,
  445.                                       apr_file_t *old_file,
  446.                                       apr_pool_t *p);
  447.  
  448. /**
  449.  * duplicate the specified file descriptor and close the original
  450.  * @param new_file The old file that is to be closed and reused
  451.  * @param old_file The file to duplicate
  452.  * @param p        The pool to use for the new file
  453.  *
  454.  * @remark *arg1 MUST point at a valid apr_file_t. It cannot point at NULL
  455.  */
  456. APR_DECLARE(apr_status_t) apr_file_dup2(apr_file_t *new_file,
  457.                                         apr_file_t *old_file,
  458.                                         apr_pool_t *p);
  459.  
  460. /**
  461.  * Move the read/write file offset to a specified byte within a file.
  462.  * @param thefile The file descriptor
  463.  * @param where How to move the pointer, one of:
  464.  * <PRE>
  465.  *            APR_SET  --  set the offset to offset
  466.  *            APR_CUR  --  add the offset to the current position 
  467.  *            APR_END  --  add the offset to the current file size 
  468.  * </PRE>
  469.  * @param offset The offset to move the pointer to.
  470.  * @remark The third argument is modified to be the offset the pointer
  471.           was actually moved to.
  472.  */
  473. APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile, 
  474.                                    apr_seek_where_t where,
  475.                                    apr_off_t *offset);
  476.  
  477. /**
  478.  * Create an anonymous pipe.
  479.  * @param in The file descriptor to use as input to the pipe.
  480.  * @param out The file descriptor to use as output from the pipe.
  481.  * @param cont The pool to operate on.
  482.  */
  483. APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, apr_file_t **out,
  484.                                           apr_pool_t *cont);
  485.  
  486. /**
  487.  * Create a named pipe.
  488.  * @param filename The filename of the named pipe
  489.  * @param perm The permissions for the newly created pipe.
  490.  * @param cont The pool to operate on.
  491.  */
  492. APR_DECLARE(apr_status_t) apr_file_namedpipe_create(const char *filename, 
  493.                                                apr_fileperms_t perm, 
  494.                                                apr_pool_t *cont);
  495.  
  496. /**
  497.  * Get the timeout value for a pipe or manipulate the blocking state.
  498.  * @param thepipe The pipe we are getting a timeout for.
  499.  * @param timeout The current timeout value in microseconds. 
  500.  */
  501. APR_DECLARE(apr_status_t) apr_file_pipe_timeout_get(apr_file_t *thepipe, 
  502.                                                apr_interval_time_t *timeout);
  503.  
  504. /**
  505.  * Set the timeout value for a pipe or manipulate the blocking state.
  506.  * @param thepipe The pipe we are setting a timeout on.
  507.  * @param timeout The timeout value in microseconds.  Values < 0 mean wait 
  508.  *        forever, 0 means do not wait at all.
  509.  */
  510. APR_DECLARE(apr_status_t) apr_file_pipe_timeout_set(apr_file_t *thepipe, 
  511.                                                apr_interval_time_t timeout);
  512.  
  513. /** file (un)locking functions. */
  514.  
  515. /**
  516.  * Establish a lock on the specified, open file. The lock may be advisory
  517.  * or mandatory, at the discretion of the platform. The lock applies to
  518.  * the file as a whole, rather than a specific range. Locks are established
  519.  * on a per-thread/process basis; a second lock by the same thread will not
  520.  * block.
  521.  * @param thefile The file to lock.
  522.  * @param type The type of lock to establish on the file.
  523.  */
  524. APR_DECLARE(apr_status_t) apr_file_lock(apr_file_t *thefile, int type);
  525.  
  526. /**
  527.  * Remove any outstanding locks on the file.
  528.  * @param thefile The file to unlock.
  529.  */
  530. APR_DECLARE(apr_status_t) apr_file_unlock(apr_file_t *thefile);
  531.  
  532. /**accessor and general file_io functions. */
  533.  
  534. /**
  535.  * return the file name of the current file.
  536.  * @param new_path The path of the file.  
  537.  * @param thefile The currently open file.
  538.  */                     
  539. APR_DECLARE(apr_status_t) apr_file_name_get(const char **new_path, 
  540.                                            apr_file_t *thefile);
  541.  
  542. /**
  543.  * Return the data associated with the current file.
  544.  * @param data The user data associated with the file.  
  545.  * @param key The key to use for retreiving data associated with this file.
  546.  * @param file The currently open file.
  547.  */                     
  548. APR_DECLARE(apr_status_t) apr_file_data_get(void **data, const char *key, 
  549.                                            apr_file_t *file);
  550.  
  551. /**
  552.  * Set the data associated with the current file.
  553.  * @param file The currently open file.
  554.  * @param data The user data to associate with the file.  
  555.  * @param key The key to use for assocaiteing data with the file.
  556.  * @param cleanup The cleanup routine to use when the file is destroyed.
  557.  */                     
  558. APR_DECLARE(apr_status_t) apr_file_data_set(apr_file_t *file, void *data,
  559.                                            const char *key,
  560.                                            apr_status_t (*cleanup)(void *));
  561.  
  562. /**
  563.  * Write a string to a file using a printf format.
  564.  * @param fptr The file to write to.
  565.  * @param format The format string
  566.  * @param ... The values to substitute in the format string
  567.  * @return The number of bytes written
  568.  */ 
  569. APR_DECLARE_NONSTD(int) apr_file_printf(apr_file_t *fptr, const char *format, ...)
  570.         __attribute__((format(printf,2,3)));
  571.  
  572. /**
  573.  * set the specified file's permission bits.
  574.  * @param fname The file (name) to apply the permissions to.
  575.  * @param perms The permission bits to apply to the file.
  576.  * @warning Some platforms may not be able to apply all of the available 
  577.  *      permission bits; APR_INCOMPLETE will be returned if some permissions 
  578.  *      are specified which could not be set.
  579.  *
  580.  *      Platforms which do not implement this feature will return APR_ENOTIMPL.
  581.  */
  582. APR_DECLARE(apr_status_t) apr_file_perms_set(const char *fname,
  583.                                            apr_fileperms_t perms);
  584.  
  585. /**
  586.  * Set attributes of the specified file.
  587.  * @param fname The full path to the file (using / on all systems)
  588.  * @param attributes Or'd combination of
  589.  * <PRE>
  590.  *            APR_FILE_ATTR_READONLY   - make the file readonly
  591.  *            APR_FILE_ATTR_EXECUTABLE - make the file executable
  592.  * </PRE>
  593.  * @param attr_mask Mask of valid bits in attributes.
  594.  * @param cont the pool to use.
  595.  * @remark This function should be used in preference to explict manipulation
  596.  *      of the file permissions, because the operations to provide these
  597.  *      attributes are platform specific and may involve more than simply
  598.  *      setting permission bits.
  599.  * @warning Platforms which do not implement this feature will return
  600.  *      APR_ENOTIMPL.
  601.  */
  602. APR_DECLARE(apr_status_t) apr_file_attrs_set(const char *fname,
  603.                                              apr_fileattrs_t attributes,
  604.                                              apr_fileattrs_t attr_mask,
  605.                                              apr_pool_t *cont);
  606.  
  607. /**
  608.  * Create a new directory on the file system.
  609.  * @param path the path for the directory to be created.  (use / on all systems)
  610.  * @param perm Permissions for the new direcoty.
  611.  * @param cont the pool to use.
  612.  */                        
  613. APR_DECLARE(apr_status_t) apr_dir_make(const char *path, apr_fileperms_t perm, 
  614.                         apr_pool_t *cont);
  615.  
  616. /** Creates a new directory on the file system, but behaves like
  617.  * 'mkdir -p'. Creates intermediate directories as required. No error
  618.  * will be reported if PATH already exists.
  619.  * @param path the path for the directory to be created.  (use / on all systems)
  620.  * @param perm Permissions for the new direcoty.
  621.  * @param cont the pool to use.  */
  622. APR_DECLARE(apr_status_t) apr_dir_make_recursive(const char *path,
  623.                                                  apr_fileperms_t perm,
  624.                                                  apr_pool_t *pool);
  625.  
  626. /**
  627.  * Remove directory from the file system.
  628.  * @param path the path for the directory to be removed.  (use / on all systems)
  629.  * @param cont the pool to use.
  630.  */                        
  631. APR_DECLARE(apr_status_t) apr_dir_remove(const char *path, apr_pool_t *cont);
  632.  
  633. /**
  634.  * get the specified file's stats.
  635.  * @param finfo Where to store the information about the file.
  636.  * @param wanted The desired apr_finfo_t fields, as a bit flag of APR_FINFO_ values 
  637.  * @param thefile The file to get information about.
  638.  */ 
  639. APR_DECLARE(apr_status_t) apr_file_info_get(apr_finfo_t *finfo, 
  640.                                           apr_int32_t wanted,
  641.                                           apr_file_t *thefile);
  642.  
  643.  
  644. /**
  645.  * Truncate the file's length to the specified offset
  646.  * @param fp The file to truncate
  647.  * @param offset The offset to truncate to.
  648.  */
  649. APR_DECLARE(apr_status_t) apr_file_trunc(apr_file_t *fp, apr_off_t offset);
  650.  
  651. /**
  652.  * Retrieve the flags that were passed into apr_file_open()
  653.  * when the file was opened.
  654.  * @return apr_int32_t the flags
  655.  */
  656. APR_DECLARE(apr_int32_t) apr_file_flags_get(apr_file_t *f);
  657.  
  658. /**
  659.  * Get the pool used by the file.
  660.  * @return apr_pool_t the pool
  661.  */
  662. APR_POOL_DECLARE_ACCESSOR(file);
  663.  
  664. /**
  665.  * Set a file to be inherited by child processes.
  666.  * @param file The file to enable inheritance.
  667.  *
  668.  */
  669. APR_DECLARE(void) apr_file_inherit_set(apr_file_t *file);
  670.  
  671. /**
  672.  * Unset a file from being inherited by child processes.
  673.  * @param file The file to disable inheritance.
  674.  */
  675. APR_DECLARE(void) apr_file_inherit_unset(apr_file_t *file);
  676.  
  677. /** @deprecated @see apr_file_inherit_set */
  678. APR_DECLARE(void) apr_file_set_inherit(apr_file_t *file);
  679.  
  680. /** @deprecated @see apr_file_inherit_unset */
  681. APR_DECLARE(void) apr_file_unset_inherit(apr_file_t *file);
  682.  
  683. /**
  684.  * Open a temporary file
  685.  * @param fp The apr file to use as a temporary file.
  686.  * @param templ The template to use when creating a temp file.
  687.  * @param flags The flags to open the file with. If this is zero,
  688.  *              the file is opened with 
  689.  *              APR_CREATE | APR_READ | APR_WRITE | APR_EXCL | APR_DELONCLOSE
  690.  * @param p The pool to allocate the file out of.
  691.  * @ingroup apr_file_open
  692.  * @remark   
  693.  * This function  generates  a unique temporary file name from template.  
  694.  * The last six characters of template must be XXXXXX and these are replaced 
  695.  * with a string that makes the filename unique. Since it will  be  modified,
  696.  * template must not be a string constant, but should be declared as a character
  697.  * array.  
  698.  *
  699.  */
  700. APR_DECLARE(apr_status_t) apr_file_mktemp(apr_file_t **fp, char *templ,
  701.                                           apr_int32_t flags, apr_pool_t *p);
  702.  
  703. #ifdef __cplusplus
  704. }
  705. #endif
  706. /** @} */
  707. #endif  /* ! APR_FILE_IO_H */
  708.